<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>easykf-2.04: Kalman Filters</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">easykf-2.04
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Kalman Filters </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro_sec"></a>
Introduction</h1>
<p>Two algorithms are implemented and all of them taken from the PhD of Van Der Merwe "Sigma-Point Kalman Filters for Probabilistic Inference in Dynamic State-Space Models" :<br/>
</p>
<ul>
<li>UKF for parameter estimation, Algorithm 6, p. 93<br/>
</li>
<li>UKF for state or joint estimation, additive noise case, Algorithm 8, p. 108 <br/>
</li>
</ul>
<h2><a class="anchor" id="usage"></a>
Usage</h2>
<p>To use the library, you simply need to :</p>
<ul>
<li>define a parameter and state structure, which depends on the algorithm you use : ukf_*_param, ukf_*_state</li>
<li>call the proper function initializing the state : ukf_*_init()</li>
<li>iterate with the proper function by providing a sample <img class="formulaInl" alt="$ (x_i, y_i) $" src="form_0.png"/> : ukf_*_iterate()</li>
<li><p class="startli">free the memory : ukf_*_free() To use these functions, you simply need to define you evolution/observation functions, provided to the ukf_*_iterate functions as well as the samples.<br/>
</p>
<p class="startli"><b>Warning :</b> Be sure to always use gsl_vector_get and gsl_vector_set in your evolution/observation functions, never access the fiels of the vectors with the data array of the gsl_vectors.<br/>
</p>
</li>
</ul>
<h2><a class="anchor" id="param_estimation"></a>
UKF for parameter estimation</h2>
<p>For UKF for parameter estimation, two versions are implemented : in case of a scalar output or vectorial output. The vectorial version works also in the scalar case but is more expensive (memory and time) than the scalar version when the output is scalar.<br/>
 For the <b>scalar</b> version :</p>
<ul>
<li>the structures to define are <a class="el" href="structukf_1_1parameter_1_1ukf__param.html" title="Structure holding the parameters of the Unscented Kalman Filter. ">ukf::parameter::ukf_param</a> and <a class="el" href="structukf_1_1parameter_1_1ukf__scalar__state.html" title="Pointer to the function to approximate in the scalar case. ">ukf::parameter::ukf_scalar_state</a></li>
<li>the methods to initialize, iterate, evaluate and free are : <a class="el" href="namespaceukf_1_1parameter.html#a4f5d4fb6f2a2be962a1528a40f8c9562" title="Allocation of the vectors/matrices and initialization. ">ukf::parameter::ukf_scalar_init</a> , <a class="el" href="namespaceukf_1_1parameter.html#ae4830e1c0b576662494d63623dcf59dc" title="Iteration for UKF for parameter estimation, in case of a scalar output. ">ukf::parameter::ukf_scalar_iterate</a> , <a class="el" href="namespaceukf_1_1parameter.html#a9b3034fa2b941068c2fc0fea41cbd5fb" title="Evaluation of the output from the sigma points. ">ukf::parameter::ukf_scalar_evaluate</a> , <a class="el" href="namespaceukf_1_1parameter.html#a18d91f67e6de67928a223b50950ffdae" title="Free of memory allocation. ">ukf::parameter::ukf_scalar_free&lt;BR&gt;</a></li>
</ul>
<p>Examples using the scalar version : <br/>
</p>
<ul>
<li>Training a simple MPL on the XOR problem : example-001.cc</li>
<li>Training a MLP on the extended XOR : example-002.cc</li>
<li>Training a RBF for fitting a sinc function : example-003.cc</li>
<li>Finding the minimum of the Rosenbrock banana function : example-006.cc</li>
</ul>
<p>For the <b>vectorial</b> version :</p>
<ul>
<li>the structures to define are <a class="el" href="structukf_1_1parameter_1_1ukf__param.html" title="Structure holding the parameters of the Unscented Kalman Filter. ">ukf::parameter::ukf_param</a> and <a class="el" href="structukf_1_1parameter_1_1ukf__state.html" title="Structure holding the matrices manipulated by the unscented kalman filter in the vectorial case...">ukf::parameter::ukf_state</a></li>
<li>the methods to initialize, iterate, evaluate and free are : <a class="el" href="namespaceukf_1_1parameter.html#ad83710f24d64d3b511ff60aa4fc90f03" title="Allocation of the vectors/matrices and initialization. ">ukf::parameter::ukf_init</a> , <a class="el" href="namespaceukf_1_1parameter.html#aa7af8ceffba2f9288b2d7b86ed57159f" title="Iteration for the statistical linearization. ">ukf::parameter::ukf_iterate</a> , <a class="el" href="namespaceukf_1_1parameter.html#aaf6c5a1c836abd3dd07c27a3eec2d097" title="Evaluation of the output from the sigma points. ">ukf::parameter::ukf_evaluate</a> , <a class="el" href="namespaceukf_1_1parameter.html#a3edd781b5248176b7404889c96e6a962" title="Free of memory allocation. ">ukf::parameter::ukf_free&lt;BR&gt;</a></li>
</ul>
<p>Examples using the vectorial version : <br/>
</p>
<ul>
<li>Training a 2-2-3 MLP to learn the OR, AND, XOR functions : example-004.cc</li>
<li>Training a 2-12-2 MLP to learn the Mackay Robot arm data : example-005.cc</li>
</ul>
<h2><a class="anchor" id="joint_ukf"></a>
Joint UKF</h2>
<p>The Joint UKF tries to estimate both the state and the parameters of a system. The structures/methods related to Joint UKF are :</p>
<ul>
<li><a class="el" href="structukf_1_1state_1_1ukf__param.html" title="Structure holding the parameters of the statistical linearization. ">ukf::state::ukf_param</a> and <a class="el" href="structukf_1_1state_1_1ukf__state.html" title="Structure holding the matrices manipulated by the statistical linearization in the vectorial case for...">ukf::state::ukf_state</a> for the parameters and the state representations</li>
<li><a class="el" href="namespaceukf_1_1state.html#ad6760ca25736be80b2b9e9f9cbe9f8e8" title="Allocation of the vectors/matrices and initialization. ">ukf::state::ukf_init</a>, <a class="el" href="namespaceukf_1_1state.html#a07694a4f76574d87caf4b1e756ccae00" title="Free of memory allocation. ">ukf::state::ukf_free</a>, <a class="el" href="namespaceukf_1_1state.html#a3a0665674b96f3e979ca39d9d4583f43" title="UKF-additive (zero-mean) noise case, &quot;Kalman Filtering and Neural Networks&quot;, p.233. ">ukf::state::ukf_iterate</a>, <a class="el" href="namespaceukf_1_1state.html#a2b40e84fd304480317cc6f0736a058fc" title="Evaluation of the output from the sigma points. ">ukf::state::ukf_evaluate</a> for respectively initializing the structures, freeing the memory, iterating on one sample and evaluating the observation from the sigma points.<br/>
 To see how to use Joint UKF, have a look to the example example-007.cc where we seek the parameters and state of a Lorentz attractor.</li>
</ul>
<h1><a class="anchor" id="install_sec"></a>
Installation and running</h1>
<h2><a class="anchor" id="tools_subsec"></a>
Requirements:</h2>
<p>In addition to a g++ compiler with the standard libraries, you also need to install :</p>
<ul>
<li>GSL (Gnu Scientific Library), available here : <a href="http://www.gnu.org/software/gsl/">http://www.gnu.org/software/gsl/</a></li>
<li>cmake for compilation</li>
</ul>
<h2><a class="anchor" id="compilation"></a>
Compilation, Installation</h2>
<p>The installation follows the standard, for example on Linux : mkdir build cd build cmake .. -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX=&lt;the prefix="" where="" you="" want="" the="" files="" to="" be="" installed&gt;=""&gt; make make install</p>
<p>It will compile the library, the examples, the documentation and install them.</p>
<h1><a class="anchor" id="example"></a>
Example outputs</h1>
<h2><a class="anchor" id="example1"></a>
Example 1 : Learning XOR with a 2-2-1 MLP</h2>
<p>Running (maybe several times if falling on a local minima) example-001-xor, you should get the following classification :</p>
<div class="image">
<img src="example-001.png" alt="example-001.png"/>
<div class="caption">
XOR classification</div></div>
<p> An example set of learned parameters is :</p>
<p>x[0] &ndash; (9.89157) &ndash;&gt; y[0] <br/>
 x[1] &ndash; (4.18644) &ndash;&gt; y[0]<br/>
 Bias y[0] : 8.22042<br/>
</p>
<p>x[0] &ndash; (10.7715) &ndash;&gt; y[1]<br/>
 x[1] &ndash; (4.18047) &ndash;&gt; y[1]<br/>
 Bias y[1] : -8.70185<br/>
</p>
<p>y[0] &ndash; (6.9837) &ndash;&gt; z<br/>
 y[1] &ndash; (-6.83324) &ndash;&gt; z<br/>
 Bias z : -3.89682<br/>
</p>
<p>The transfer function is a sigmoid : <img class="formulaInl" alt="$ f(x) = \frac{2}{1 + exp(-x)}-1$" src="form_1.png"/></p>
<h2><a class="anchor" id="example2"></a>
Example 2 : Learning the extended XOR with a 2-12-1 MLP and a parametrized transfer function</h2>
<p>Here we use a 2-12-1 MLP, with a sigmoidal transfer function, to learn the extended XOR problem. The transfer function has the shape : <img class="formulaInl" alt="$f(x) = \frac{1}{1.0 + exp(-x)}$" src="form_2.png"/></p>
<p>The classification should look like this :</p>
<div class="image">
<img src="example-002.png" alt="example-002.png"/>
<div class="caption">
Extended XOR classification</div></div>
 <h2><a class="anchor" id="example3"></a>
Example 3 : Approximating the sinc function with a Radial Basis Function network</h2>
<p>In this example, we use a RBF network with 10 kernels to approximate the sinc function on [-5.0,5.0] To make the life easier for the algorithm, we evenly spread the centers of the gaussians on [-5.0, 5.0].</p>
<p>The results are saved in 'example-003.data', the first column contains the x-position, the second column the result given by the trained RBF and the last column the value of sinc(x)</p>
<div class="image">
<img src="example-003.png" alt="example-003.png"/>
<div class="caption">
RBF learning the sinc function</div></div>
 <h2><a class="anchor" id="example4"></a>
Example 4 : Using a 2-2-3 MLP to learn three boolean functions : XOR, AND, OR</h2>
<h2><a class="anchor" id="example5"></a>
Example 5 : Using a 2-12-2 MLP to learn the Mackay-robot arm problem</h2>
<p>In this example, we learn the two outputs (x,y) from the inputs (theta, phi) of the Mackay-robot arm dataset. For this we train a 2-12-2 MLP with a parametrized sigmoidal transfer function.</p>
<div class="image">
<img src="example-005-x.png" alt="example-005-x.png"/>
<div class="caption">
Learning the x-component</div></div>
 <div class="image">
<img src="example-005-y.png" alt="example-005-y.png"/>
<div class="caption">
Learning the y-component</div></div>
 <h2><a class="anchor" id="example6"></a>
Example 6 : Finding the minimum of the Rosenbrock banana function</h2>
<p>We use here UKF for parameter estimation to find the minimum of the Rosenbrock banana function : <img class="formulaInl" alt="$ f(x,y) = (1 - x)^2 + 100 ( y - x^2)^2 $" src="form_3.png"/><br/>
</p>
<div class="image">
<img src="example-006.png" alt="example-006.png"/>
<div class="caption">
Minimisation of the Rosenbrock banana function</div></div>
 <h2><a class="anchor" id="example7"></a>
Example 7 : Finding the parameters of a Lorentz attractor</h2>
<p>In this example, we try to find the parameters (initial condition, evolution parameters) of a noisy lorentz attractor. The dynamic of the lorentz attractor is defined by the three equations :</p>
<p><img class="formulaInl" alt="$ \frac{dx}{dt} = \sigma ( y - x ) $" src="form_4.png"/> <br/>
 <img class="formulaInl" alt="$ \frac{dy}{dt} = x (\rho - z) - y $" src="form_5.png"/> <br/>
 <img class="formulaInl" alt="$ \frac{dz}{dt} = xy - \beta z $" src="form_6.png"/> <br/>
 While observing a noisy trajectory of such a Lorentz attractor, the algorithm tries to find the current state and the evolution parameters <img class="formulaInl" alt="$ (\sigma, \rho, \beta)$" src="form_7.png"/>. The samples we provide are <img class="formulaInl" alt="$ (t_i, {x(t_i), y(t_i), z(t_i)})$" src="form_8.png"/>.</p>
<p>To clearly see how UKF catches the true state, we initialized the estimated state of UKF to -15, -15 , -15<br/>
</p>
<div class="image">
<img src="example-007-rms.png" alt="example-007-rms.png"/>
<div class="caption">
Learning RMS</div></div>
 <div class="image">
<img src="example-007.png" alt="example-007.png"/>
<div class="caption">
Estimated state with the true state and its noisy observation</div></div>
<p> <br/>
<br/>
 </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
